

<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Installation guidelines &mdash; IVRE  documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
      <link rel="stylesheet" type="text/css" href="../_static/graphviz.css?v=4ae1632d" />

  
      <script src="../_static/jquery.js?v=5d32c60e"></script>
      <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="../_static/documentation_options.js?v=5929fcd5"></script>
      <script src="../_static/doctools.js?v=9bcbadda"></script>
      <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Configuration" href="config.html" />
    <link rel="prev" title="Installation" href="index.html" /> 
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            IVRE
              <img src="../_static/logo.png" class="logo" alt="Logo"/>
          </a>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul>
<li class="toctree-l1"><a class="reference internal" href="../overview/index.html">Overview</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Installation</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Installation guidelines</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#database">Database</a></li>
<li class="toctree-l3"><a class="reference internal" href="#dependencies">Dependencies</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#external-programs">External programs</a></li>
<li class="toctree-l4"><a class="reference internal" href="#python">Python</a></li>
<li class="toctree-l4"><a class="reference internal" href="#databases">Databases</a></li>
<li class="toctree-l4"><a class="reference internal" href="#web">Web</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#ivre">IVRE</a></li>
<li class="toctree-l3"><a class="reference internal" href="#configuration">Configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="#initialization">Initialization</a></li>
<li class="toctree-l3"><a class="reference internal" href="#getting-ip-data">Getting IP data</a></li>
<li class="toctree-l3"><a class="reference internal" href="#using-agents">Using Agents</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="config.html">Configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="fast-install-and-first-run.html">Fast install &amp; first run</a></li>
<li class="toctree-l2"><a class="reference internal" href="docker.html">Docker</a></li>
<li class="toctree-l2"><a class="reference internal" href="agents.html">Agents</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../usage/index.html">Usage</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../dev/index.html">Development</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Licenses:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../license.html">IVRE: GPL v3</a></li>
<li class="toctree-l1"><a class="reference internal" href="../license-external.html">Licenses for external files</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">IVRE</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">Installation</a></li>
      <li class="breadcrumb-item active">Installation guidelines</li>
      <li class="wy-breadcrumbs-aside">
            <a href="../_sources/install/installation.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="installation-guidelines">
<h1>Installation guidelines<a class="headerlink" href="#installation-guidelines" title="Link to this heading"></a></h1>
<section id="database">
<h2>Database<a class="headerlink" href="#database" title="Link to this heading"></a></h2>
<p>Depending on the backends you wan to use, install a database
server. Please keep in mind that currently, MongoDB is currently the
only supported backend for all the purposes. To learn more about the
different purposes, read the <a class="reference internal" href="../overview/principles.html#principles"><span class="std std-ref">Principles</span></a>.</p>
<p>The database servers installation and setup is not covered here, and
depends on your platform and needs. Please refer to the server
documentation on how to install it. For MongoDB you can read <a class="reference external" href="http://docs.mongodb.org/manual/installation/">the
installation section</a>
of their documentation.</p>
</section>
<section id="dependencies">
<h2>Dependencies<a class="headerlink" href="#dependencies" title="Link to this heading"></a></h2>
<section id="external-programs">
<h3>External programs<a class="headerlink" href="#external-programs" title="Link to this heading"></a></h3>
<p>If you plan to run scans from a machine, install <a class="reference external" href="https://nmap.org/">Nmap</a>, <a class="reference external" href="https://github.com/robertdavidgraham/masscan">Masscan</a>, and/or <a class="reference external" href="https://zmap.io/">Zmap / Zgrab
/ Zgrab2</a>. If you want to integrate screenshots,
install <a class="reference external" href="https://github.com/tesseract-ocr/tesseract">Tesseract</a>,
<a class="reference external" href="https://www.imagemagick.org/">ImageMagick</a>, <a class="reference external" href="http://ffmpeg.org/">FFmpeg</a> and <a class="reference external" href="http://phantomjs.org/">PhantomJS</a>.</p>
<p>If you plan to analyze PCAP file on a machine, install, depending on
your needs:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://www.zeek.org/">Zeek</a> (previously known as Bro, version 3
minimum).</p></li>
<li><p><a class="reference external" href="http://qosient.com/argus/">Argus</a>.</p></li>
<li><p><a class="reference external" href="http://nfdump.sourceforge.net/">Nfdump</a>.</p></li>
</ul>
</section>
<section id="python">
<h3>Python<a class="headerlink" href="#python" title="Link to this heading"></a></h3>
<p>To install IVRE, you’ll need <a class="reference external" href="http://www.python.org/">Python</a> 3.11
minimum, with the following modules:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://bottlepy.org/">bottle</a>.</p></li>
<li><p><a class="reference external" href="https://cryptography.io/en/latest/">cryptography</a>.</p></li>
<li><p><a class="reference external" href="http://api.mongodb.org/python/">pymongo</a> version 3.7 minimum.</p></li>
<li><p><a class="reference external" href="https://tinydb.readthedocs.io/">tinydb</a>, to use the
<strong>experimental</strong> TinyDB backend (this does not require a database
server).</p></li>
<li><p><a class="reference external" href="http://www.sqlalchemy.org/">sqlalchemy</a> and <a class="reference external" href="http://initd.org/psycopg/">psycopg2</a> to use the <strong>experimental</strong> PostgreSQL
backend.</p></li>
<li><p><a class="reference external" href="https://github.com/elastic/elasticsearch-py">elasticsearch</a> and
<a class="reference external" href="https://github.com/elastic/elasticsearch-dsl-py">elasticsearch-dsl</a> to use the
<strong>experimental</strong> Elasticsearch backend.</p></li>
<li><p><a class="reference external" href="http://www.pythonware.com/products/pil/">PIL</a> optional, to trim
screenshots.</p></li>
<li><p><a class="reference external" href="https://pypi.org/project/pyOpenSSL/">pyOpenSSL</a> version 16.1.0
minimum, optional, to parse X509 certificates (a fallback exists
that calls <code class="docutils literal notranslate"><span class="pre">Popen()</span></code> the <code class="docutils literal notranslate"><span class="pre">openssl</span></code> binary and parses its output,
but it is much slower and less reliable).</p></li>
</ul>
</section>
<section id="databases">
<h3>Databases<a class="headerlink" href="#databases" title="Link to this heading"></a></h3>
<p>IVRE’s reference backend service is <a class="reference external" href="https://www.mongodb.org/">MongoDB</a>, version 3.6 minimum. It is highly
suggested that you use the latest stable release (the performances
tend to improve a lot).</p>
<p>The <code class="docutils literal notranslate"><span class="pre">passive</span></code>, <code class="docutils literal notranslate"><span class="pre">nmap</span></code> and <code class="docutils literal notranslate"><span class="pre">view</span></code> purposes have an
<strong>experimental</strong> PostgreSQL backend that can be used in lieu of
MongoDB.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">view</span></code> purpose has an <strong>experimental</strong> Elasticsearch backend. It
can be used to create views accessible to other Elasticsearch tools,
such as Kibana (see <a class="reference internal" href="../usage/kibana.html#ivre-with-kibana"><span class="std std-ref">IVRE with Kibana</span></a>).</p>
<p>Please refer to the database servers (or your distribution)
documentation on how to install and configure them.</p>
</section>
<section id="web">
<h3>Web<a class="headerlink" href="#web" title="Link to this heading"></a></h3>
<p>For production services, it is recommended to install either <a class="reference external" href="https://httpd.apache.org/">Apache</a> with the <a class="reference external" href="https://modwsgi.readthedocs.io/en/develop/">WSGI module</a>, or <a class="reference external" href="https://www.nginx.com/">Nginx</a> with <a class="reference external" href="https://uwsgi-docs.readthedocs.io/en/latest/">uWSGI</a>.</p>
<p>IVRE can use <a class="reference external" href="https://www.dokuwiki.org/dokuwiki">Dokuwiki</a> as its
notepad, it is also recommended to install it.</p>
<p>Please refer to the servers (or your distribution) documentation on
how to install and configure them.</p>
<p>Configuration file samples are provided in IVRE’s source repository,
under <code class="docutils literal notranslate"><span class="pre">pkg/apache</span></code> and <code class="docutils literal notranslate"><span class="pre">pkg/nginx</span></code>. Also, the
<a class="reference internal" href="docker.html#docker"><span class="std std-ref">Docker</span></a> creation files in <code class="docutils literal notranslate"><span class="pre">docker/web*</span></code> can
provide useful examples.</p>
<p>If you do not want (or cannot) to install a Web server, you can try
IVRE’s integrated server, suited for tests or tiny installations. Just
run <code class="docutils literal notranslate"><span class="pre">ivre</span> <span class="pre">httpd</span></code>!</p>
</section>
</section>
<section id="ivre">
<h2>IVRE<a class="headerlink" href="#ivre" title="Link to this heading"></a></h2>
<p>The installation of IVRE itself can be done:</p>
<ul>
<li><p>On <a class="reference external" href="https://www.kali.org/">Kali</a>, just install the <a class="reference external" href="https://pkg.kali.org/pkg/ivre">package</a> by running <code class="docutils literal notranslate"><span class="pre">apt</span> <span class="pre">update</span> <span class="pre">&amp;&amp;</span> <span class="pre">apt</span>
<span class="pre">install</span> <span class="pre">ivre</span></code>. You can also install <code class="docutils literal notranslate"><span class="pre">ivre-doc</span></code> if needed.</p></li>
<li><p>On <a class="reference external" href="https://getfedora.org/fr/">Fedora</a>, you can use the <a class="reference external" href="https://copr.fedorainfracloud.org/coprs/">Copr
package</a>; follow the
<a class="reference external" href="https://copr.fedorainfracloud.org/coprs/pessoft/IVRE/">instructions</a>.</p></li>
<li><p>On other RPM-based Linux distributions, you can easily build RPM
packages (using the provided <code class="docutils literal notranslate"><span class="pre">pkg/buildrpm</span></code> script, or use the
<code class="docutils literal notranslate"><span class="pre">setup.py</span></code> script with your own options).</p></li>
<li><p>On <a class="reference external" href="https://www.archlinux.org/">Arch Linux</a>, there are <a class="reference external" href="https://aur.archlinux.org/">AUR</a> packages that can be installed using
<a class="reference external" href="https://aur.archlinux.org/packages/yay/">yay</a> for example. The
packages are:</p>
<blockquote>
<div><ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">ivre</span></code>: the main package, which depends on <code class="docutils literal notranslate"><span class="pre">python-ivre</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">python-ivre</span></code> the Python library.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ivre-web</span></code>: the Web application.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ivre-docs</span></code>: the documentation.</p></li>
</ul>
</div></blockquote>
<p>These packages are based on the latest stable version; they all have
a <code class="docutils literal notranslate"><span class="pre">-git</span></code> version, based on the current development code from the
<a class="reference external" href="https://github.com/ivre/ivre">Github repository</a>. You can install
for example <code class="docutils literal notranslate"><span class="pre">ivre-git</span></code> and <code class="docutils literal notranslate"><span class="pre">ivre-web-git</span></code> if you want to test
the latest developments.</p>
<p>All the packages are based on the same bases: <a class="reference external" href="https://aur.archlinux.org/pkgbase/ivre/">ivre</a> and <a class="reference external" href="https://aur.archlinux.org/pkgbase/ivre-git/">ivre-git</a>.</p>
</li>
<li><p>On <a class="reference external" href="https://blackarch.org/">BlackArch Linux</a> (an Arch Linux-based
penetration testing distribution) IVRE is packaged (and installed in
the Live ISO).</p></li>
<li><p>Using <a class="reference external" href="https://pypi.org/project/pip">pip</a>: run <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span>
<span class="pre">ivre</span></code> (this will download and install for you <a class="reference external" href="https://pypi.org/project/ivre">the IVRE package</a> and its Python dependencies from
PyPI, the Python Package Index).</p></li>
<li><p>From the source code, using the <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> (classical <code class="docutils literal notranslate"><span class="pre">./setup.py</span>
<span class="pre">build;</span> <span class="pre">sudo</span> <span class="pre">./setup.py</span> <span class="pre">install</span></code>) script.</p></li>
<li><p>Using <a class="reference internal" href="docker.html#docker"><span class="std std-ref">Docker</span></a> (in this case you do not need to
follow the instructions in
<a class="reference internal" href="#configuration"><span class="std std-ref">Configuration</span></a>, as the Docker containers
are already configured).</p></li>
</ul>
</section>
<section id="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Link to this heading"></a></h2>
<p>You can set configuration values in several files:</p>
<ul class="simple">
<li><p>system-wide: <code class="docutils literal notranslate"><span class="pre">ivre.conf</span></code> in the following directories: <code class="docutils literal notranslate"><span class="pre">/etc/</span></code>,
<code class="docutils literal notranslate"><span class="pre">/etc/ivre</span></code>, <code class="docutils literal notranslate"><span class="pre">/usr/local/etc</span></code>, <code class="docutils literal notranslate"><span class="pre">/usr/local/etc/ivre</span></code>.</p></li>
<li><p>user-specific: <code class="docutils literal notranslate"><span class="pre">~/.ivre.conf</span></code> (read after the system-wide
configuration files, so highest priority).</p></li>
<li><p>execution-specific: another configuration file can be specified
using the <code class="docutils literal notranslate"><span class="pre">$IVRE_CONF</span></code> environment variable.</p></li>
</ul>
<p>The configuration files are Python files. They may set, for example,
the variable <code class="docutils literal notranslate"><span class="pre">DB</span></code> to use a different database than the default
one.</p>
<p>See <a class="reference internal" href="config.html#configuration"><span class="std std-ref">Configuration</span></a> to learn more about the
different configuration parameters.</p>
</section>
<section id="initialization">
<h2>Initialization<a class="headerlink" href="#initialization" title="Link to this heading"></a></h2>
<p>Once IVRE has been properly configured, it’s time to initialize its
databases.</p>
<p>For that, the command-line tools (namely <code class="docutils literal notranslate"><span class="pre">ivre</span> <span class="pre">ipinfo</span></code>, <code class="docutils literal notranslate"><span class="pre">ivre</span>
<span class="pre">scancli</span></code>, <code class="docutils literal notranslate"><span class="pre">ivre</span> <span class="pre">view</span></code>, <code class="docutils literal notranslate"><span class="pre">ivre</span> <span class="pre">flowcli</span></code> and <code class="docutils literal notranslate"><span class="pre">ivre</span>
<span class="pre">runscansagentdb</span></code>, respectively for information about IP addresses,
passive information, active information and running scans through
agents) have a <code class="docutils literal notranslate"><span class="pre">--init</span></code> option.</p>
<p>So you can run, with a user or from a host where the configuration has a
write access to the database (add <code class="docutils literal notranslate"><span class="pre">&lt;</span> <span class="pre">/dev/null</span></code> to skip the
confirmation):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ yes | ivre ipinfo --init
$ yes | ivre scancli --init
$ yes | ivre view --init
$ yes | ivre flowcli --init
$ yes | sudo ivre runscansagentdb --init
</pre></div>
</div>
</section>
<section id="getting-ip-data">
<h2>Getting IP data<a class="headerlink" href="#getting-ip-data" title="Link to this heading"></a></h2>
<p>To fetch the IP address data files (mainly from <a class="reference external" href="https://www.maxmind.com/">Maxmind</a>) and parse them (required if you want to
scan or list all IP addresses from a country or an AS), just run the
following command (it takes a long time, usually more than 40 minutes
on a decent server):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo ivre ipdata --download
</pre></div>
</div>
<p>It is advised to run this command on a regular basis (e.g.,
weekly). If you use IVRE on several machines, you may want to run the
command on one machine and create an <code class="docutils literal notranslate"><span class="pre">ivre-data</span></code> package containing
the files under the <code class="docutils literal notranslate"><span class="pre">/usr/share/ivre/geoip</span></code> directory (or distribute
those files somehow).</p>
<p>The URLs downloaded are stored in the configuration. By default, the
following files are downloaded:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python
&gt;&gt;&gt; from ivre.config import IPDATA_URLS
&gt;&gt;&gt; for fname, url in IPDATA_URLS.items():
...     print(&quot;%s: %s&quot; % (fname, url))
...
GeoLite2-City.tar.gz: https://ivre.rocks/data/geolite/GeoLite2-City.tar.gz
GeoLite2-City-CSV.zip: https://ivre.rocks/data/geolite/GeoLite2-City-CSV.zip
GeoLite2-Country.tar.gz: https://ivre.rocks/data/geolite/GeoLite2-Country.tar.gz
GeoLite2-Country-CSV.zip: https://ivre.rocks/data/geolite/GeoLite2-Country-CSV.zip
GeoLite2-ASN.tar.gz: https://ivre.rocks/data/geolite/GeoLite2-ASN.tar.gz
GeoLite2-ASN-CSV.zip: https://ivre.rocks/data/geolite/GeoLite2-ASN-CSV.zip
GeoLite2-dumps.tar.gz: https://ivre.rocks/data/geolite/GeoLite2-dumps.tar.gz
iso3166.csv: https://dev.maxmind.com/static/csv/codes/iso3166.csv
BGP.raw: https://thyme.apnic.net/current/data-raw-table
</pre></div>
</div>
</section>
<section id="using-agents">
<h2>Using Agents<a class="headerlink" href="#using-agents" title="Link to this heading"></a></h2>
<p>If you do not plan to run active scans with remote agents (where IVRE
will not be installed), you can skip this section.</p>
<p>The agent does not require IVRE to be installed. It is a script that
needs to be adapted to each situation.</p>
<p>The agent is only needed when you cannot install IVRE on the machine
used to scan or when you want to use several machines to run one scan.</p>
<p>It requires a POSIX environment, and the commands <code class="docutils literal notranslate"><span class="pre">screen</span></code>,
<code class="docutils literal notranslate"><span class="pre">rsync</span></code> and <code class="docutils literal notranslate"><span class="pre">nmap</span></code> (of course). See the
<a class="reference internal" href="agents.html#agents"><span class="std std-ref">Agents</span></a> documentation for more information about
that.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="index.html" class="btn btn-neutral float-left" title="Installation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="config.html" class="btn btn-neutral float-right" title="Configuration" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2011 - 2025, Pierre LALET.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>